<script type="text/html" data-help-name="uib-cache">
    <p>
        A simple caching node that works with <span class="uib-name"><span class="uib-red">UI</span>BUILDER</span>.
    </p>
    <p>
        See <a href="./uibuilder/techdocs/#/cache-node" target="_blank">Documentation: Using the cache node</a> for more detail.
    </p>

    <h3>Inputs</h3>
    <p>
        Any msg can be sent into the node.
    </p>
    <p>
        In addition, the node recognises uibuilder control messages for cache replay and cache clear.<br>
        See <a href="./uibuilder/techdocs/#/pre-defined-msgs" target="_blank">Documentation: pre-defined messages</a> 
        for the structure of those messages.
    </p>

    <h3>Outputs</h3>
    <p>
        Any non-uibuilder-control message is passed to the output.
    </p>
    <p>
        If the node receives a REPLAY or "client connect" (where the connections count is zero) control message, all of the cached messages are sent to the output.
    </p>
    <p>
        Upon replay, the output messages will have the socket id of the control message (if present) added
        so that the replayed messages are sent to the correct client. Any socket id saved in the cached messages
        is ignored.
    </p>
    <p>
        Upon replay, the output messages will also get a <code>_uib.cache</code> property added with a value of "REPLAY".
        This can be used in your front-end code if you need to differentiate between original and replayed messages.
    </p>
    <p>
        If the node receives a CLEAR control message, all of the cached messages are deleted and nothing is sent to the output.
    </p>

    <h3>Node Settings</h3>
    <dl class="message-properties">
        <dt>Cache by <span class="property-type">string</span></dt>
        <dd>
            Enter an incoming message property to group cached entries by.<br>
            When choosing a property to group by, be mindful of the number of messages
            that may end up in the cache. If too many large messages are cached, Node-RED <b>WILL</b> crash.<br>
            The default entry is "topic".
        </dd>

        <dt>Cache individually? <span class="property-type">boolean</span></dt>
        <dd>
            If selected, the "Cache by" field will be hidden. All messages will be
            cached as a single group.
        </dd>

        <dt>Only replay cache when client is really new <span class="property-type">boolean</span></dt>
        <dd>
            If selected, when a "client connect" control message is received, the cache will only
            be sent if <code>msg.connections</code> is zero. That indicates that the client connection
            is actually a new one and node a reconnection. This is now the default as it reduces the number
            of times the cache is sent and does not send if the client is simply waking up (when it doesn't need the cache.)
        </dd>

        <dt># messages <span class="property-type">integer</span></dt>
        <dd>
            The maximum number of messages <b>per group</b> that will be cached.<br>
            Once the max number is reached, the oldest messages will be dropped.<br>
            If you change this number and re-deploy, the node will automatically trim
            the number of messages cached.<br>
            You can use a number of zero to allow an infinite number of cached entries,
            however, you need to take great care in that case not to exceede the available
            memory, the node will not check for you.<br>
            The default number is one. This means that the last recorded message for each group
            will be replayed which is generally the expected result.
        </dd>

        <dt>Use Store <span class="property-type">Drop-down</span></dt>
        <dd>
            The drop-down is pre-populated with the <code>contextStorage</code> modules you define in <code>settings.js</code>.
            You can use this to choose a persistent context store if desired so that the cache survives system restarts.<br>
            If you change this value, you may need to manually delete the old version of the node context variable to avoid confusion.
            Select the node, view the Context Data side-panel, refresh the entries and delete the appropriate <code>uib_cache</code> entry.
        </dd>

        <dt>Store Type <span class="property-type">Drop-down</span></dt>
        <dd>
            One of "Node", "Flow", or "Global".<br>
            Take care if using "Flow" or "Global" since other nodes and flow might make changes to the cache.<br>
            "Node" is the default and should usually be used since there can be no name clashes or external influence.
        </dd>

        <dt>Variable <span class="property-type">string</span></dt>
        <dd>
            Default: "uib_cache". This is the store variable name that will be used.<br>
            Take care if using flow/global stores and multiple cache nodes since a name clash will result in the same cache being used.
        </dd>

        <dt>Name <span class="property-type">string</span></dt>
        <dd>A short description shown in the admin interface.</dd>
    </dl>

    <p>
        <b>NOTE</b> that there is an example flow in the examples library that demonstrates the use of this node.
        Use the Editor's menu, import, Examples, node-red-contrib-uibuilder and import the <code>uib-cache-test</code> example.
    </p>
</script>
